Skip to content

feat: support scan planning and pushdown for Java table providers - #119

Open
wirybeaver wants to merge 2 commits into
apache:mainfrom
wirybeaver:feat/java-table-scan-pushdown
Open

wirybeaver wants to merge 2 commits into
apache:mainfrom
wirybeaver:feat/java-table-scan-pushdown

Conversation

@wirybeaver

@wirybeaver wirybeaver commented Oct 28, 2026 •

Copy link
Copy Markdown

Which issue does this PR close?

Closes #118.

Rationale for this change

Java table providers currently receive no physical scan request. A selective source cannot choose an access path from pushed predicates, read only projected columns, or distinguish exact filtering from candidate pruning. Expose that existing DataFusion contract while keeping the Java/JNI binding thin and source-agnostic.

What changes are included in this PR?

Add scanWithArgs(ScanArgs) and supportsFiltersPushdown to TableProvider. Providers can report pushdown support per filter and use the requested projection, filters and limit to build an ExecutionPlan without opening a reader. The default scanWithArgs defers to the existing scan(allocator) at execution time.

DataFusion optimizer -> Java filter capabilities
DataFusion planning  -> scanWithArgs(ScanArgs) -> ExecutionPlan
DataFusion execution -> plan.execute(partition, allocator) -> fresh ArrowReader -> Arrow C stream -> Rust operators

DataFusion still owns residual filtering and limit placement. Providers may return the requested projected schema or the full registered schema. The adapter projects full-schema batches when needed, preserving row counts even for zero-column results. Source-specific access-path decisions stay in provider implementations; no storage SDK or DataFusion Rust-core change is introduced.

This remains a bounded, single-partition leaf-scan API, not a binding for arbitrary child-consuming physical operators.

Are these changes tested?

A Java/JNI/Arrow integration harness registers an in-memory selective source and inspects its planned requests and actual reads. EXPLAIN plans without opening the source; execution requests only the matching row and projected column. Inexact and unsupported predicates retain residual evaluation before LIMIT, exact predicates permit limit pushdown, and independent scans keep separate requests and readers. The existing full-schema provider path is exercised through the same native boundary.

The source is synthetic: this does not establish performance or correctness against an external storage service.

Are there any user-facing changes?

The new TableProvider methods, ScanArgs and ExecutionPlan are additive. ExecutionPlan.execute(int partition, BufferAllocator allocator) receives partition 0 in this single-partition implementation. Existing TableProvider and SimpleTableProvider implementations need no changes. The provider guide documents projection, filter, limit, threading and reader-ownership contracts.

@wirybeaver
wirybeaver force-pushed the feat/java-table-scan-pushdown branch from 268a98f to 0b3a113 Compare October 29, 2026 06:08
@wirybeaver
wirybeaver marked this pull request as ready for review October 29, 2026 14:58
@wirybeaver
wirybeaver marked this pull request as draft October 29, 2026 15:30
Expose scanWithArgs and filter capabilities as default TableProvider methods with immutable ScanArgs. Plan a lazy ExecutionPlan before execution while retaining existing full-schema providers; execute receives an explicit partition index.

Forward DataFusion filter capabilities and preserve residual-filter/limit semantics without source-specific dependencies or DataFusion-core changes. Cover the Java/JNI/Arrow path with selective-source integration tests.
@wirybeaver
wirybeaver force-pushed the feat/java-table-scan-pushdown branch from 0b3a113 to c1869ed Compare November 2, 2026 01:05
@wirybeaver
wirybeaver marked this pull request as ready for review November 2, 2026 06:10
@wirybeaver

Copy link
Copy Markdown
Author

@andygrove Would you mind taking a review of this PR? Our team's service is in Java and needs to pass customized execution plan.

@andygrove andygrove left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this, and for turning pgwhalen's feedback around so quickly. The tests are thorough. They cover EXPLAIN planning without opening a reader, residual filters before LIMIT for inexact and unsupported filters, limit pushdown for exact filters, empty projection for COUNT(*), and independent scans under UNION ALL. I built it locally and clippy and the TableProvider* tests pass.

Could you update the PR description to match the current API? It still mentions ScanTableProvider, TableScanRequest, TableScan and planScan. The description becomes the squash commit message, so it would be good to have it describe scanWithArgs, ScanArgs and ExecutionPlan.

I left two inline comments on the API shape.

* filter. Limits outside the non-negative Java {@code long} range are not forwarded; DataFusion
* still applies the query's limit.
*/
public record ScanArgs(

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This exposes the generated LogicalExprNode as public API. That type tracks DataFusion's datafusion.proto for the bundled version, and its package is excluded from our Javadoc. Pushdown code that matches on BinaryExpr ops and literal variants, like the test's SelectiveSource, could break when we bump DataFusion. I think passing the proto is a reasonable first step, but should we say in table-provider.md that the expression format follows DataFusion's proto and may change between DataFusion versions? It would be good to agree on that compatibility story before this ships in a release.

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In my own java bindings I'd original made it a goal for the expression APIs (logical and physical) to use their own POJOs of sealed classes and records where it made sense, with the hope of the API feeling friendlier, and hiding the generated classes unless the caller wanted to pass them. I backed off voicing that goal when I saw the protos start to get exposed in this repo and I couldn't really explain why I thought it was important. You do highlight one possible compatibility issue that swings me back in the other direction.

@pgwhalen pgwhalen Nov 21, 2026 •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW, here is my working draft of the "public API" agent instructions that I mentioned wanting to do many months ago. I have larger ambitions for it but tried to slim it down for what is realistic right now.

If that seems directionally correct and only require small tweaks, I'd be happy to open a proper PR. There are some minor divergences from the rules there which I could open up follow-up PRs for.

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done. The guide and ScanArgs Javadoc explain that LogicalExprNode follows the bundled DataFusion version; providers should decline unfamiliar forms with UNSUPPORTED and retest on upgrade. I’d keep a stable Java expression model as a separate API discussion.

Leave scanWithArgs as the optional planning hook. Document that pushdown expressions follow the bundled DataFusion protobuf and that providers should decline unknown forms.
@wirybeaver

wirybeaver commented Nov 21, 2026 •

Copy link
Copy Markdown
Author

@andygrove The PR description now uses TableProvider.scanWithArgs(ScanArgs) and ExecutionPlan throughout, including the planning and execution diagram. The inline comments are addressed as well

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support source scan planning and pushdown for Java table providers

3 participants